Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Introduction
Part editors are required to create an ODWindow instance for each modeless platform window they create. An ODWindow contains a root frame, and thus provides the root of the layout hierarchy. This provides a means for OpenDoc to distribute events to parts, since the main event loop is within the OpenDoc shell.
There is one exception to the requirement for an ODWindow. At least on the Mac™ OS, modal dialogs can be implemented using functions like ModalDialog() which take an event filter routine as a parameter. In this case an ODWindow is not necessary in order to receive events. See Dialogs.
ODWindow is a fairly thin cover for a platform window pointer. For some operations, the part editor will have to retrieve the platform window pointer from the ODWindow, and use platform facilities. An example would be the programmatic resizing of a window when the user clicks in the zoom box.
This document describes how to create, register, open and close windows. See also Opening a Part into a Window, Window Events, Dialogs, Shared Utility Windows and Activation.
Creating a Window
Part editors create windows using the standard facilities of the platform. In the case of the Mac OS, the NewCWindow call is used.
New in DR4: The memory for the window record is allocated from the OpenDoc heap. This is not an absolute requirement, but is highly desirable, to reduce the impact on the application heap.
Note: Part editors should pass kODFalse for the "isVisible" parameter. Once the window is registered, the Show() method will be called to show it. This is a consequence of the implementation of floating windows in OpenDoc.
Registering a Window
An ODWindow instance is created by registering a platform window with the ODWindowState object, which is obtained from the session like other session-wide services:
fWindowState = fSession->GetWindowState(ev);
There are two similar methods for registering a window. RegisterWindow() creates and returns an ODWindow containing a newly-created root frame belonging to the supplied root part.
kODFrameObject, // frame type - kODFrameObject or // kODNonPersistentFrameObject
kODTrue, // is root window - i.e. "Keeps the document open"
kODFalse, // is resizable - OpenDoc will draw the resize icon
kODFalse, // is floating
kODTrue, // should save - saved as part of the document
kODFalse, // should dispose - part will dispose platform window
fPartWrapper, // root part
fFrameView, // Tokenized View Type - icon, thumbnail etc.
fSettingsPresentation, // Tokenized Presentation
kODNULL); // Source frame
RegisterWindowForFrame() is similar, but takes an existing root frame as a parameter
window = windowState->RegisterWindowForFrame(ev,
platformWindow,
kODFrameObject,
isRootWindow,
isResizable,
isFloating,
shouldSave,
shouldDispose,
sourceFrame);
New in DR2: RegisterWindowForFrame is used when internalizing the windows of an existing document. See Opening a Part into a Window.
New in DR3: Parts can call the ODWindow method SetDontDispose() to tell OpenDoc not to dispose of the platform window when deleting the ODWindow. This can be used to reduce the impact of the part on the application heap, by having the part manage the storage for the platform window. In this case, the part will have to dispose of the window when the root frame is removed.
New in DR4: The shouldDispose property is now a parameter to RegisterWindow.
ODWindow Properties
Windows with the “is root” property set are windows that keep the document open. The shell closes the document when the last root window is closed. Most part editors will create a single root window in the Open() method, but some may create multiple root windows with different views of the document.
The “should save” property determines whether the window state saves the window persistently. This should generally be set to kODTrue for root windows, and kODFalse for non-root windows. Some parts may wish windows created using the View in Window command or the Open Selection command to be persistent. If this is the case, then additional work on the part of the part editor (no pun intended) is required, because it must persistently maintain the connection between the source frame and the window, so that the window can be closed when the source frame is deleted.
New in DR4: The “should dispose” property determines whether OpenDoc will dispose of the platform window pointer when the window is closed. If the part editor allocates the window memory from the OpenDoc heap, as is recommended, this property should be false, and the part editor should dispose of the platform window itself, typically in its DisplayFrameClosed/Removed methods.
The “frame type”, “view type” and “presentation” properties are passed on to the root frame which the window creates. The presentation property can be used by the part editor to distinguish frames and hence windows from one another during event handling.
The “source Frame” parameter is used when an embedded frame is opened into a window. In other circumstances it will be kODNULL.
Window IDs
Part editors should not hang onto ODWindow pointers, because the shell or window state may close a window and invalidate the reference. Instead, the window state assigns IDs (valid for a session), and parts can make use of the following two methods:
// returns kODNULL if the window has been removed from the window state, i.e Closed
Opening a Window
After creating and registering a window, a part editor will usually do the following:
window->Open(ev);
window->Show(ev);
window->Select(ev);
The Open() method builds the facet hierarchy, but does not make the window visible.
The Show() method makes the window visible, but does not change the window ordering.
The Select() method brings the window to the front.
Closing Windows
Under normal circumstances, the OpenDoc Shell handles the Close menu item, as well as clicks in the close box. If the window in question is the last "root window" of a draft, the draft is closed, along with all its windows. When a part editor registers a window, it indicates whether or not it is a root window.
If a window being closed is not a root window, or is not the last root window, the shell will just close that window.
Sometimes a part editor will need to close a window programmatically. For example, a part editor may wish to intercept clicks in the close box, and the Close menu item, and merely hide the window so that it can be more quickly displayed later. This may be appropriate for dialog windows, for example. In this case, the part editor will have to retain the window ID of the window, and close it programmatically at a later time. To close a window programmatically, a part editor should call ODWindow::CloseAndRemove(), after which the window object is no longer usable.
New in DR4:
If an editor allocates the platform window from the OpenDoc heap, it must dispose of it when the window is closed. One way to do this is, to store a reference to the platform window in the object stored in the part info of each frame, and then dispose of that reference in the DisplayFrameClosed/Removed methods.
